/*
 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */
package java.lang;

import java.util.Iterator;
import java.util.Objects;
import java.util.Spliterator;
import java.util.Spliterators;
import java.util.function.Consumer;

/**
 * <p>实现这个接口的类，允许成为foreach循环的目标
 * @param <T> the type of elements returned by the iterator
 *
 * @since 1.5
 * @jls 14.14.2 The enhanced for statement
 */
public interface Iterable<T> {
    /**
     * <p>返回一个iterator（T类型的）
     * @return an Iterator.
     */
    Iterator<T> iterator();

    /**
     * <p>默认方法，对iterable的所有元素作为参数执行下面的action.accept这个方法，直到抛出异常
     * <p>除非这个方法被覆盖的方法重写了，元素以iterator的顺序被执行
     * <p>被抛出的异常会被转发给调用者
     * <p>这个方法等价于下面的这个代码
     * <pre>{@code
     *     for (T t : this)
     *         action.accept(t);
     * }</pre>
     *
     * @param action iterable里的所有元素，都作为参数，一个个给action对象，然后调用它的accept方法
     * @throws NullPointerException if the specified action is null
     * @since 1.8
     */
    default void forEach(Consumer<? super T> action) {
    	//先校验这个action是否为空，如果为空则报错NullPointerException
        Objects.requireNonNull(action);
        //对这个iterable对象进行foreach循环
        for (T t : this) {
            action.accept(t);
        }
    }

    /**
     * <p>创建一个spliterator覆盖这个iterable包含的元素。
     * 
     * <p>默认的实现从iterable的iterator创建一个早期绑定的spliterator。
     * 这个spliterator从iterable的iterator继承fail-fast属性。
     * 
     * <p>默认的实现应该通常被覆盖。默认实现返回的spliterator有很差的分割能力，没有报告大小，不能报告任何特征。
     * 实现的类应该接近总是提供一个更好的实现。
     *
     * @return a {@code Spliterator} over the elements described by this
     * {@code Iterable}.
     * @since 1.8
     */
    default Spliterator<T> spliterator() {
    	//用iterable的iterator结果作为参数，特征直接设置为0，啥都没有
        return Spliterators.spliteratorUnknownSize(iterator(), 0);
    }
}
